One of the most useful functions of PH is its ability to schedule Timed Events in the future on a one-shot, or repeating basis.
The Timed Event control window is accessed via PH Explorer, and offers a wide range of control choices.
To set up a Timed Event right-click on any row and select "Insert" from the pop-up menu. This will create a new row, where you clicked, so you can enter a new event. The rows are sorted by the ID column. If you wish to update the window and have it sorted after you have made entry(s), press F5 on your keyboard.
Start by entering a descriptive name for your event in the
ID column.
NOTE: The
Disabled column lets you enable or disable a timed event. If Disabled the Event Scheduling will be ignored by PH.
The
Start Time column cells are grayed out because they are not user accecssible, but are the sytem calculated datetime value representing the actual scheduled event time based on the user entered Reference Time/Offset/Offset Amount data values.
Select a fixed or dynamic
Timing property depending on whether the event is to be scheduled to occur at a specific time or at a varying time related to day/night cycles. NOTE: if the later, in order for sunrise/sunset calculations to be correct, your geographic location MUST be setup in the PH Explorer>Setup>Sun window.
Next set the Frequency the event should occur. The frequency can be directly specified in (integer) Minutes (eg, 10) or in a variety of predefined time periods such as Hourly, Daily, Weekly, etc.
The Frequency pull-down menu can be used to select one of an extensive number of these predefined periods, including special days like "4th of July".
The last part of this FAQ document describes how to create your own custom special periods, such as "Every Other Tuesday" using Timed Event Formulas.
The specified Frequency can have an Offset associated with it to create a "lived in" appearance for lighting ( the Random attributes to keep perps at bay) or Absolute offsets (eg, to schedule something for 20 minutes after sunrise). Most often the default "None" choice will be used.
If an Offset (other than None) is selected, then a value in (integer) minutes must also be specified in the Offset Amnt column.
If you select "Exact" in the Timing column then you must enter a datetime in the Reference Time column. You can enter a datetime value directly in the Reference Time cell or you can double-click the cell which will open up a dialog window where you can pick a calendar date and edit the time values.
You can skip this step if your Timing column entry is one of the dynamic time choices, since the Reference Time will be automatically determined, and will vary every day.
After setting up the datetime parameters, you now specify how you want to take action(s) at the scheduled time. You can choose from four different Types of action as exampled below.
Finally NOTE that the Boolean field (as in many other PH configuration Windows) can be used to selectively enable/disable the Timed Event. The example Boolean entry here only allows the Timed Even to occur if the Global value of HOME is true. If HOME is not true, then the Timed Event will be skipped.
The following dialog explains how to creatre your own Timed Event Formulas, that will allow you to design your own custom event schedules, such as scheduling an alert every other Tuesday.
The Timed Event Formulas can be tricky, but aren't too bad once you get used to it. It helps to know how it works internally though.
A Timed Event formula MUST evaluate to a datetime type. This is a MUST. Other than that, it's just a formula and the functions under the Date/Time section of the Help file are extremely useful.
Timed Event Formulas have two special variables that come into play.
The first one is [REFTIME]. [REFTIME] is substituted for the datetime value in the "Reference Time" column of a timed event. When you are creating a brand new Timed Event, the "Reference Time" field defaults to the current date and time. If it's an existing Timed Event that has just fired and the Timed Event formula is being evaluated to determine the next reference time, it is the date and time in the reference field which is the datetime that the Timed Event was just executed at.
In a normal Timed Event with a "Daily" frequency, the reference time will be increased by 10080 which will be a full day forward. When that Timed Event is fired, all things being normal, the reference time will be current date and time. The frequency will then be "added" to the reference time to determine the new reference time. If the Frequency is a Timed Event Formula, the formula will be evaluated to determine the new reference time.
Which brings us to our second special variable.
The [INCREMENT] variable. [INCREMENT] initially starts as a value of 0 and the Timed Event formula is evaluated. If the datetime returned is less than the current datetime, 1 is added to [INCREMENT] and the Timed Event formula is evaluated again. This continues until the returned datetime is greater than the current datetime and this value becomes the new "Reference Time". So the [INCREMENT] is just a number that can be used anywhere within the Timed Event formula and increases by 1 until the formula returns a datetime in the future. You can use this [INCREMENT] value to increment the year, the day, an hour, etc.
So, if we were to create a custom Timed Event Formula to schedule an "Every Other Tuesday at 6:30AM" occurance, it would go like this:
datetime(relativedate([REFTIME],[INCREMENT] * 14 + 3 - daynumber([REFTIME]) - if(daynumber([REFTIME]) > 3,0,7)),time([REFTIME]))
[REFTIME] is substituted for whatever value is currently in the Reference Time. If this a brand new Timed Event, it will be the current date and time.
If the Timed Event has already been working, it should be the Date and Time that the Timed Event has fired which should be Tuesday.
Since [REFTIME] is the "Reference Time" value which is actually a date AND a time, we should extract out the invidual date and time components using the date() and time() functions respectively.
The relativedate function accepts a date and an offset amount in days to determine a new date.
The daynumber function accepts a date and tells you what number of the day in the week that date falls on. Sunday is 1, Monday is 2, and so on to Saturday, which is 7.
Sun Mon Tue Wed Thu Fri Sat
1 2 3 4 5 6 7
If you are creating the Timed Event for the first time, the reference time will the current date and time which may be either before Tuesday of the current week or after Tuesday of the current week. Since it makes no sense to create a Timed Event in the past, the formula is designed to set the Reference Time to whatever the next Tuesday is.
So, lets walk our way through it for the case where the example formula is assumed to be created on Sunday 01/18/2015.
Tuesdays are the 3rd day of the week (thus the "3" occuring in the Timed Event Formula example above).
We're creating the Timed Event for the first time, so [INCREMENT] will start out as 0.
Substituting 0 for [INCREMENT], we have 0 * 14 + 3 --> 3
Substituting 1 for daynumber(2015-01-18) (where 2015-01-18 is the formula creation time [REFTIME]) we have --> 1
The next part of the equation contains an if statement which looks like: if(daynumber(date([REFTIME])) > 3,7,0).
This is basically trying to determine if we're evaluating this formula on a day before or on Tuesday (Sun, Mon, Tue) or a day after Tuesday (Wed, Thurs, Fri, Sat).
If the daynumber of [REFTIME] (2015-01-18 in our case or 1) is greater than 4, then return 7 else return 0. Since 1 is less than 4, we have --> 0.
So our formula is now 3 - 1 - 0 which equals 2.
Thus our relativedate function will take the Sunday initial date (2015-01-18) and add 2 which will give us a date of 2015-01-20 (Tuesday).
We take that date as well as the time component of the [REFTIME] and create a datetime value for 2015-01-20.
Now, lets say the Timed Event is running as normal, it's Tuesday and the Timed Event has just executed.
We now need to evaluate the formula to determine the new Reference Time for when the Timed Event will run again.
Lets say the date is 2015-01-20 (Tuesday). Lets also say the [REFTIME] time component was 13:00:00. [INCREMENT] of course starts at 0.
So we have 0 * 14 + 3 - 3 (for this part of the formula: [INCREMENT] * 14 + 4 - daynumber(date([REFTIME]))). This equates to 0.
The if statement also equates to 0 since the daynumber of the current reftime is 3 and 3 is not greater than 4.
So our offset amount for the relativedate function is 0 and the date portion is today.
So the relativedate function will return 2015-01-20 and the time component of reftime is 13:00:00.
Thus the total datetime value returned is 2015-01-20 13:00:00.
This is compared to the current date/time. Since all Timed Events are actually executed 1 second after their scheduled time (this is by design), this returned time will automatically be less than the current time (the soonest of which would be 2015-01-20 13:00:01).
Now 1 is added to the [INCREMENT] variable, resulting in a value of 1 and we repeat the formula.
[INCREMENT] * 14 + 3 - daynumber(date([REFTIME]))
which substitutes out to: 1 * 14 + 3 - 3 which equals 14. The if statement still evaluates to 0. The result of the relativedate function will therefore be 14 days in the future (2 weeks) from the current date which will be Tuesday, 2015-02-03.
This is combined with the time component of reftime which is 13:00:00 yielding a new datetime of 2015-02-03 13:00:00. This is compared with the current date/time and since it's in the future, evaluation stops and the new reference time is set.